package za.org.jcicada.genss.lifecycle;

import za.org.jcicada.genss.SystemURN;
import za.org.jcicada.genss.messages.Result;



/**
 * ILifeCycleSubject.java
 *
 * @author Simon Cross
 *
 * Created on November 11, 2008, 14:16
 */


/**
 * Generic software system lifecycle control interface. 
 *
 * @todo The following methods from the MagicDraw version
 * of the interface are not included: 
 *  - getLogList ()
 *  - getLog (logId)
 * Inclusion of the first two will depend on logging being
 * sorted out.
 */
public interface ILifeCycleServer {
    
    /**
     * Define possible behaviours for shutdown.
     */
    enum Shutdown {
        
        /**
         * The system should terminate completely on completion of shutdown.
         */
        HALT,
        
        /**
         * The system should restart after completion of shutdown.
         */
        RESTART
    }
    
    /**
     * Callback interface required for the life cycle server to notify the 
     * system of events.
     */
    public interface ICallback {
        
        /**
         * Trigger the system to shutdown
         * @param behaviour tell if the system should restart or halt
         * @return object describing the result of the request
         */
        Result shutdown(Shutdown behaviour);
        
        /**
         * Set the log level for the specified system
         * @param level the desired log level
         * @return object describing the result of the request
         */
        Result setLogLevel(LogLevel level);
        
        /**
         * Request that the specified system perform a reconnect to
         * external devices.
         * @return object describing the result of the request
         */
        Result reconnect();
        
        /**
         * Ping the subsystem
         * @return object describing the result of the request
         */
        Result ping();
    }

    // requests (replies in ILifeCycleClient).

    /**
     * Halt the software subsystem.
     */
    void requestHalt(ILifeCycleClient observer, SystemURN systemURN);

    /**
     * Restart the software subsystem.
     */
    void requestRestart(ILifeCycleClient observer, SystemURN systemURN);

    /**
     * Set the subsystem logging level.
     * @param observer The observer making the request
     * @param level The desired log level
     */
    void requestSetLogLevel(ILifeCycleClient observer, SystemURN systemURN, LogLevel level);
    
    /**
     * Reconnect the specified subsystem
     * @param observer the observer making the request
     * @param systemURN the subsystem to reconnect
     */
    void requestReconnect(ILifeCycleClient observer, SystemURN systemURN);
    
    /**
     * Request a ping reply 
     * @param observer The observer making the request
     * @param systemURN the subsystem pinged
     */
	void requestPing(ILifeCycleClient observer, SystemURN systemURN);
    
    /**
     * Inform the server that the client has disconnected.
     */
    void informDisconnect(ILifeCycleClient observer);

}
